perf(gc): seed promote-on-first-copy from a completed mark-sweep (#7598) - #7613

Closes #7598. The promote-on-first-copy remainder of #7592.

The waste

On promote-heavy workloads every long-lived object is copied twice — Eden →
survivor by one copying minor, survivor → old by the next. json_pipeline at
500k, on main:

The same 268 MB, moved twice. gc/tenuring.rs already computes the right
condition — the survival-rate lock — but it keys on prev_copied, so it needs a
previous copying minor to have filled the survivor space. It engaged for cycle
4, which is exactly why the waste is confined to cycle 3.

Route chosen: P1 from the design note — seed the decision from a completed

non-copying collection

The other two were considered and rejected on this workload:

• P3 (size-based pretenuring) is a poor fit. These records are ~100–200 byte
  objects, so any PretenureSizeThreshold low enough to catch them catches
  almost everything, and its stated failure mode — a parse-and-discard loop over
  large buffers promoting pure garbage — is real and not bounded by anything the
  collector measures. It is a good idea whose threshold must come from a suite
  sweep, not from this workload.
• P2 (per-age-band entry decisions) is a refinement of P1, not an
  alternative: it buys precision, and the problem here is latency.

The obstacle is that retune_after_scavenge is fed only by copying minors,
so full mark-sweeps and non-copying minor fallbacks feed the loop nothing — and
once a workload escalates to those, the loop goes blind exactly when it is
needed. But every collection on that path already walks every Eden header and
classifies it live or dead. That census answers the same question one collection
earlier.

So: at the end of any such sweep, when

1. the surviving Eden cohort alone exceeds the desired survivor occupancy
   (compute_target_survivals(...) == 1 — the module's existing rule, only
   read from a different place), and
2. ≥90% of the Eden bytes the sweep classified were live (the "an aging round
   would filter nothing" proof, measured instead of inferred),

engage the existing PROMOTE_LOCK so the next copying minor enters at S=1.

Exit is deliberately not this signal — it stays the existing influx-based
unlock, which is already threshold-invariant and already tested, so the seed
cannot introduce an enter/exit oscillation of its own.

Why this signal is not a fixed point of the policy reading it

This issue has produced three self-referential signals already, so here is the
argument rather than the assumption.

The failures were all the same shape: a signal suppressed by the state it is
supposed to leave. promoted_bytes is zero by construction at S=4, so "was
the promotion rate high?" can never answer yes while S=4 holds. #7596's first
nursery cap gated from-space occupancy on a total that included from-space, so
it was a bound from-space could never cross. #7594's handoff scheduled a
non-moving full to relieve pressure only a moving cycle can relieve.

The Eden live/dead split has none of that structure, for a structural reason:
it is produced by the mark-sweep's own arena walk. Marks come from
reachability from roots; neither the mark phase nor the sweep walk reads
tenuring_survivals(). The threshold is consulted in exactly one place —
copying.rs's per-object move — and this path does not run it. So the signal is
not merely observed to survive at S=4; it cannot be a function of S at all.

Measurably, at both endpoints:

Measured on this workload: eden_live_bytes=279,964,968 eden_dead_bytes=896 live_pct=99 desired=1,048,576 seeds=true — taken while S was still 4.

Determinism (#7432)

#7432 forbids re-deciding S while objects are being moved, because the
copied/promoted split would then depend on root traversal order. The seed is
written at the END of a completed sweep and read at the ENTRY of a later copying
minor (CopyingNurseryCollector::new snapshots it once), so every object in a
cycle still sees exactly one threshold.

Two exclusions at the callsite keep the input deterministic too, and both are
refusals rather than tuning:

• Budgeted cycles — whole-cycle allocate-black marks every mid-cycle birth,
  and this walk reads MARKED as live, so a churn workload's births would read as
  a ~100% live Eden. Same reason the age-bump is suppressed there.
• Cycles that ran the conservative native-stack scan — that scan retains
  whatever the stack happens to look like a pointer to, by an amount that varies
  run to run (benchmarks/gc_ratchet/README.md measures 8.28 MB / 16% of one
  probe's reported retention). A liveness measurement taken under it is not
  sound, and feeding it to a policy would make the gated copy/promote counters
  non-deterministic.

No new env knob. The PERRY_GC_DIAG line prints the census and the verdict on
every sweep, including refusals — a policy that silently declines is
indistinguishable from one that never ran.

Measurements

Copy census — the halving signature, per cycle

Semantic counters, PERRY_GC_TRACE=1, output hash identical on every row.
500k:

This is promotion, not cadence. Cycles 1–3 are unchanged in kind, trigger,
old_before and eden_live — cycle 3 receives the same 280,997,080 bytes to
the byte and merely sends them somewhere else. The cycle that disappears is
baseline cycle 4, whose entire content was the second copy: its own Eden influx
was 1.0 MB and it promoted the 268 MB cycle 3 had just parked in the survivor
space. Removing it is removing the waste, not lengthening the collection
interval.

Totals:

Bytes moved: 0.498× at 200k, 0.499× at 500k. Halved, as the design note's
signature requires.

On the anti-vacuity gate. The design note asks for copied_objects > 0 && promoted_bytes > 0 on any cited run. The main arm satisfies both literally.
The changed arm cannot satisfy the first clause because eliminating that copy is
the change; what the clause exists to catch — the #7024/#7025 shape where the
fast arm ran zero collections — is refuted directly: it ran 3 collections,
one of them a copying minor that moved 4,117,015 objects / 280,997,080 bytes
([gc-copy-minor] ran … eligible=true fallback=none). Reported as
moved_objects > 0 rather than copied_objects > 0.

Wall and RSS — pinned quiet host

perry-macos (M1, 8 GB), load ~1.6, 5 interleaved reps per size, warmup
discarded, PERRY_NO_AUTO_OPTIMIZE=1, prebuilt static archives, output
byte-identical (cmp) on every row.

Spread within each arm was ≤0.03 s on wall and ≤0.25 MB on RSS across the 5
reps.

RSS goes DOWN, which is the opposite of what the design note expected. The
note assumed promoting earlier raises the old-gen high-water mark. It does — but
it removes a larger term: with S=4 the 268 MB cohort exists twice at once at
the peak, as Eden from-space plus survivor to-space. Promoting on first copy
means the peak holds one copy. This is the first change in this campaign whose
wall-time win does not have to be traded against RSS.

gc-ratchet — the official check, on the #7609 baseline

This is the first GC-pacing change since 2026-08-01 that could be gated properly,
so it was run as a two-arm check on the pinned host: once with a main
(d4342fff3) build, once with this branch, back to back in the same session, both
built with the same -p perry -p perry-runtime-static -p perry-stdlib-static set.
The main arm establishes what the two commits of drift since the pin
(26b9c9d59) cost on their own, so anything the second arm moves is attributable
to this change.

gc-ratchet (check) at d4342fff3  (main arm)     → gc-ratchet: OK
gc-ratchet (check) at 3aa3b091c  (this branch)  → gc-ratchet: OK

Diffing the two arms' 144-cell tables: every semantic cell is bit-identical.
heap_used_bytes, heap_total_bytes, minor_cycles, step_cycles,
copied_objects, copied_bytes, promoted_objects, promoted_bytes,
freed_bytes — all twelve probes, no difference at all. The only rows that
differ are rss_bytes, peak_rss_bytes and wall_ms, which move in both
arms and stay inside band. The largest is 12_large_live_set.peak_rss_bytes:
+0.36% on the main arm, +0.68% on this one (190,955,520 → 191,561,728, a 606 KB
difference on a 190 MB probe, band 3%). It is not a promotion effect — that
probe's promoted_bytes is identical to the byte in both arms.

12_large_live_set.wall_ms — #7610's unexplained +13.58% flag, now gated:

This change does not move that cell (1 ms apart). Separately, and worth
recording on #7610: the +13.58% did not reproduce in this session at all — a
main build measures 3,016 ms against the 3,471 ms the artifact pinned three
commits earlier on the same host, i.e. the regression reads as reversed. That
is a data point for #7610, not a claim by this PR.

The subject was live — and where

The ratchet result above proves no collateral; it does not prove the policy
ran, because on these probes it correctly does nothing. That distinction is the
#7024/#7025 shape, so it is settled by the diagnostic rather than assumed. The
seed prints its census and its verdict on every mark-sweep, including refusals:

12_large_live_set:  [gc-tenuring] sweep-seed eden_live_bytes=12582432
                    eden_dead_bytes=22019256 live_pct=36 desired=2097152
                    seeds=false already_locked=true
json_pipeline 500k: [gc-tenuring] sweep-seed eden_live_bytes=279964968
                    eden_dead_bytes=896 live_pct=99 desired=1048576
                    seeds=true already_locked=false

So on the largest-live-set probe the rule is evaluated and declined — by the
survival-rate half, at 36% — and on the target workload it is evaluated and
accepted. A policy that silently declines is indistinguishable from one that
never ran; this is why the refusal branch prints.

Sabotage verification

Each mutation was applied to the shipped code and the named tests re-run. All
four turn red, and the tree is green again after restoring:

Gates (local — CI backlog is deep, so this is the evidence)

cargo test -p perry-runtime --no-fail-fast 1885 passed, 0 failed ·
cargo fmt --all -- --check clean · check_file_size.sh OK ·
raw_handle_debt.py 998 (baseline 998) · addr_class_inventory.py passed ·
class_id_collisions.py passed. No codegen change (the diff is four files, all
under crates/perry-runtime/src/gc/, 314 insertions and no deletions), so the
root-dominance corpus is not implicated.

What this does not do

• No new env knob. The PERRY_GC_DIAG line uses the existing one, so the
  kill-policy has nothing new to carry (and gc: PERRY_GEN_GC_EVACUATE=0 moves zero cells on all 12 gc-ratchet probes — the knob's off-state is unexercised #7611 has nothing to add to).
• It does not touch cadence. The full's census is deliberately not fed to
  retune_nursery_cap_scale; collection pacing stays exactly where perf(gc): break the survivor-promotion handoff livelock (#7592) #7594 and
  perf(gc): live-proportional collection budgets at both generations (#7592) #7596 left it.
• It does not close allocation-site pretenuring. perf(gc): allocation-site pretenuring — long-lived cohorts are copied twice (Eden→survivor→old) #7598 also proposed static
  "allocated in a loop and stored into an accumulator that outlives it" proof.
  This removes the double copy for cohorts a mark-sweep can see; a workload whose
  first collection is already a copying minor still pays one wasted copy, and
  that is what the static route would cover.

Collateral check on GC-shaped workloads outside the ratchet

Six micro-workloads the ratchet does not contain, both arms, semantic counters
and stdout compared. tree is the workload the survival-rate lock was written
for (medium-lived cohorts that do die in the survivor space — the failure mode
this rule must not trip on); retain is the accumulator shape; churn and
push_cls are pure churn.

deeplist's 528-byte / 3-object delta is stable across 3 runs per arm, so it is
deterministic rather than noise — and it is not a policy effect. It lands
entirely in cycle 1, a copying minor entered at S=4, while this workload's
first mark-sweep is cycle 3 — so no seed had been evaluated yet and the tenuring
state at cycle 1 is identical in both arms. It is the collector's documented
address-sensitive component in copied_objects (gc_ratchet/README.md: "a
sub-0.1% host-dependent component") showing up between two differently-laid-out
binaries. For the record, the seed is reached later on this workload and
reports live_pct=100 seeds=true already_locked=true — the copying path had
already locked, so it changes nothing.

Reproducibility of the cited numbers

The change arm was rebuilt from the committed tree (-p perry -p perry-runtime-static -p perry-stdlib-static, pinned PERRY_RUNTIME_DIR,
PERRY_NO_AUTO_OPTIMIZE=1) and json_pipeline 500k re-run against it: 3
collections, copied_bytes 0, promoted_bytes 280,997,080, output
byte-identical to the main arm. The committed source reproduces the census
above.

Summary by CodeRabbit

• Performance

  • Improved garbage collection by promoting highly live memory directly during the next collection cycle, reducing redundant copying and memory movement.
  • Added safeguards to preserve predictable behavior for budgeted collections and conservative stack scanning.

• Bug Fixes

  • Improved Eden memory accounting during collection, distinguishing retained and reclaimed memory more accurately.

• Documentation

  • Added release documentation describing the promotion improvements and measured performance benefits.